<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en"><head>
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	<title>Registration For TurboGears</title>
	<meta name="generator" content="TextMate http://macromates.com/">
	<meta name="author" content="Patrick Lewis">
	<link rel="stylesheet" type="text/css" href="style.css">
	</head><body>
<h1>Registration for TurboGears</h1>

<h2>What Is It?</h2>
    <p>The registration package is a set of templates for <a href="http://www.turbogears.org/">TurboGears</a>
applications designed to make common tasks associated with new user
registration and maintenance easier. It is intended to interface with
the TurboGears identity framework. Some features are: </p>
    <ul>
        <li>A new user registration form</li>
        <li>Email validation</li>
        <li>Inserts validated users into groups you define</li>
        <li>Lost password recovery</li>
        <li>Allows users to change their password and email address</li>
        <li>Users can delete their accounts</li>
    </ul>
    
<h2>Who Can Use It?</h2>

    <p>If your identity model is fairly
similar to the standard identity model, and uses the same user/group/permissions
layout, you are a pretty good candidate. If your identity model is
significantly different, you will have some work to do to integrate the
registration templates, and it may be easier to start from scratch. </p>
    
    <p>TurboGears version 1.0 (or greater) is
required. Currently, only Python 2.4 and 2.5 is supported. </p>
    
<h2>Installation</h2>
    
    <p>If you have TurboGears installed, you should already have the easy_install program.  The module should install with:
    </p>    
        
    <pre>easy_install registration</pre>
    
    <p>You may need to use sudo or something similar to elevate your permissions appropriately.</p>
    
<h2>Upgrading</h2>
   <p>
      To upgrade from a previous version of registration, use easy_install as follows:
   </p>
   
   <pre>easy_install -U registration</pre>
    
<h2>Setting Things Up</h2>

<h3>Add the Templates to your Project</h3>
    
    <p>If you have an existing project, you can add the registration files with the following command:</p>
        
        <pre>tg-admin update -t registration</pre>
        
    <p>If
this is your first time installing registration in this project, you
can safely say 'n' to overwriting any files, unless you actually want
to replace them.</p>
    
    <p> If you are upgrading the templates in
your project from a previous version of registration, you can say 'n'
to any files that aren't in a 'registration' folder. For the registration
templates, it is probably safest to answer 'b' (for backup), which will
put in the upgraded code/templates, and save a backup of your original
version. Once the update is complete, you can compare the old and new
versions to see if there are any changes you may have made that will
need to be incorporated into the new templates. </p>

        
    <p>For new projects, the command is:</p>
    
        <pre>tg-admin quickstart -t 'turbogears registration'</pre>
    

<h3>Set Up the Model</h3>
    
    <p>If your model User class has been
modified from the original User that 'tg-admin quickstart' provides,
you will need to modify the registration.model.RegistrationPendingUser
class to look like your model (or at least as much as you want the user
to have to fill out when they register.) Basically, you can cut and
paste from your User model into RegistrationPendingUser, but be sure
not to delete 'validation_key' column in the new class.</p>

   <p>
      To create the registration tables in your database, the easiest way is 
      to use the 'create_registration_tables' function, like this:
   </p>
   <pre>plewis% tg-admin shell
Python 2.5.1 (r251:54869, Apr 18 2007, 22:08:04) 
[GCC 4.0.1 (Apple Computer, Inc. build 5367)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
(CustomShell)
>>> import myproject.registration.model as model
>>> model.create_registration_tables()</pre>
   
   
        
<h3>Set Configuration Variables</h3>
        <p>In your project's
config folder, there should be a new file named 'registration.cfg'. You
will need to edit the values as appropriate. The purpose for most
variables should be documented in the comments of the file.</p>
    
<h3>Tying Everything In</h3>

    <h4>Add in the Registration Controller</h4>
    <p>In
your main controllers.py, you need to reference the new registration
controller. If you want to expose registration off of the root of your
main controller, it would be something like: </p>
    
    <pre>from myproject.registration import controllers as reg_controllers
        
class Root(controller.RootController):
    registration = reg_controllers.UserRegistration()
    # the rest of your controller code
    </pre>
    
    <p>If
you are using the stock User and Group definitions that identity
provides, your work is done. However, if you have modified these
classes, you still have a bit to do.</p>
    
    <h4>Making Registration Fit Your Model</h4>
        
    <p>If your User class is different from the original User, you will need to modify registration in the following areas:</p><p>
        </p><ul>
            <li>in
registration.model, set class RegistrationPendingUser as appropriate
(this should have already done in the 'Set Up the Model' step above)</li>
            <li>In
registration.widgets, there is a class NewUserFields that defines the form
fields for new user entry. You should modify this to provide the
appropriate fields. </li>
            <li>In registration.widgets, there is a
class NewUserSchema that provides form validation. If you want to have
form fields validated, you will need to modify this class. </li>
            <li>In registration.controllers, the method
'create' creates a new RegistrationPendingUser based on the fields
provided from the UserFields form. You should modify the parameters
provided to 'create', as well as the fields used when the new
RegistrationPendingUser is made. </li>
            <li>In registration.controllers, the method
'promote_pending_user' should work for most cases, but if you have any
special fields that are in RegistrationPendingUser that you don't want
to move to your User class, you can modify the list of elements that
shouldn't migrate.</li>
            <li>In registration.controllers, the 'do_delete' method should be modified to do any custom user cleanup that needs to be done upon deleting a user.
            <li> In registration.widgets,
ExistingUserFields should expose elements you would like an existing
user to be able to modify </li>
            <li>
               In registration.widgets, ExisitngUserSchema provides validation for existing user data.
            </li>
        </ul>
    <p>The
registration process also assumes you can find a User
'by_email_address', and that your link to groups is named something
like 'group'. If those two cases aren't true, you have some more work
to do to make things work.</p>
    
    <p>Once these changes have been made, you can start your project and see the new exposed registration controls.</p>
    
    <h4>Template Customization</h4>
    
    <p>There
are a number of templates in the templates/registration directory that can be customized to fit in with how your site looks.</p>
    
    <p>If you would like, you can also change the login form to have a link to
the lost password page. Instead of having your login controller use the
'templates.login' template, use 'yourproject.templates.registration.login'. You may
need to fix the url in registration/login.kid to point to the correct
'lost_password' controller.</p>

<h2>Key Controllers</h2>
    <p>There are a few interesting controllers that you may want to link to in other parts of your app.</p>
    <ul>
        <li><span class="controller">new</span> - The starting point for new user registration</li>
        <li><span class="controller">lost_password</span> - Recovers lost passwords</li>
        <li><span class="controller">edit_user</span> - Allows a user to edit their email address and password.</li>
        <li><span class="controller">delete_user</span> - Allows a user to delete their account.
        </li>
        <li><span class="controller">validate_new_user</span>
- You don't want to link to this, but emails sent out by the framework
will point to this controller to validate that the user received the
email at the address they specified.</li>
        <li><span class="controller">validate_email_change</span>
- Again, don't link to this directly, but this controller is included
in emails for registered users that want to change their email address.
</li>
   </ul>

<h2>Software Details</h2>

<h3>Support</h3>

<p>Please use the <a href="http://groups.google.com/group/tg-registration">registration</a> Google Group to ask any support related questions. Ideas or comments are also welcome on that list.</p>

<p>To track development or file a bug report, please refer to the <a href="http://code.google.com/p/tg-registration/">Project page / subversion repository</a>
</p>

<h3>Download</h3>
<p>Download: <a href="http://patrickhlewis.googlepages.com/registration-0.3-py2.4.egg">registration-0.3-py2.4.egg</a> Feb 13, 2007</p>

<p><a href="http://patrickhlewis.googlepages.com/CHANGELOG.txt">Changelog</a></p>

<p></p>

<h3>License</h3>

<p>This is the <a href="http://www.opensource.org/licenses/mit-license.php">MIT License</a>.</p>

<p>Copyright (c) 2008 Patrick Lewis</p>

<p>Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation files
(the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:</p>

<p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p>

<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>
        

</body></html>